DOCUMENT 


AN IN-HOUSE 
TECHNICAL DOCUMENTATION SYSTEM 


DOCUMENTATION PRODUCTION 


FOUR MAIN GROUPS ARE INVOLVED 
@ WRITERS 

@ PRODUCTION PERSONNEL 

e@ EDITORS 

@ READERS 


EACH GROUP HAS A SET OF OBJECTIVES 


A SUCCESSFUL DOCUMENTATION PRODUCTION SYSTEM 
MUST MEET THOSE OBJECTIVES 


DOCUMENTATION PRODUCTION 


OBJECTIVES OF THE READER 
- @ ACCURATE AND COMPLETE 
@ EASY TO READ (TYPOGRAPHICALLY) 
— FONTS 
— WHITE SPACE 
® EASY TO FIND INFORMATION 
— SPATIAL ORGANIZATION (A.K.A. FORMATTING) 


— INDEX, TOC, ACCURATE XREFS, EXAMPLES, 
TABLES, FIGURES 


DOCUMENTATION PRODUCTION 


OBJECTIVES OF THE WRITER 

@ EASY TO ENTER INFORMATION 

© ACCURATE & TIMELY FEEDBACK AS TO FORMAT 
e EASY TO INCORPORATE CONTENT CHANGES 
® 


EASY TO MAINTAIN (2ND, 3RD GENERATION 
UPDATES) 


e AUTOMATION OF TEDIOUS TASKS 
— INDEX 
—- TOC 
— XREF GENERATION 


DOCUMENTATION PRODUCTION 


OBJECTIVES OF THE PRODUCTION GROUP 
e QUICK TURNAROUND. 


@ STREAMLINED, WELL-DEFINED PRODUCTION 
PROCESS 


e EASY TO ACCOMMODATE WRITERS’ /EDITORS’ 
FORMATTING REQS. 


e@ WELL DEFINED, DOCUMENTED FORMATS 


@ EASY TO INCORPORATE LAST MINUTE CONTENT 
CHANGES | 


e AUTOMATION OF TEDIOUS TASKS 
— PAGINATION 
PASTING IN RUNNING HEADS, FEET 
— ART 
PAGE NUMBERING 


DOCUMENTATION PRODUCTION 


OBJECTIVES OF THE EDITOR | 
e ACCURATE & TIMELY FEEDBACK AS TO FORMAT 
@ QUICK TURNAROUND IN PRODUCTION 


@ OUTPUT SHOULD BE HIGH QUALITY AND APTLY 
FORMATTED 


@ INFORMATION SHOULD BE WELL ORGANIZED 


DOCUMENTATION PRODUCTION 


HISTORICAL PROBLEMS 
@ OUTPUT QUALITY NOT STATE-OF-THE-ART 


© FORMATTING LANGUAGES DIFFICULT TO LEARN 
AND USE 

@ CENTRALIZED MAINTENANCE OF FILES 
CUMBERSOME 

© TRACKING OF DOCUMENTS (AMONG WRITERS, 
EDITORS, PRODUCTION GROUP) INEFFICIENT 


DOCUMENTATION PRODUCTION 


"HISTORICAL PROBLEMS 
© FORMAT CONSISTENCY DIFFICULT TO ENFORCE 


© ACCOMMODATING NEW OR COMPLEX 
FORMATS NOT EASY 


-@ FINAL PRODUCTION TIME-CONSUMING: 
— MANUAL PAGINATION 
— MANUAL PASTE-UP OF TABLES AND EXAMPLES 
— MANUAL INDEXING 


DOCUMENT: 
THE SOLUTION 


MAJOR COMPONENTS OF THE SYSTEM 
— @ SDML 

e TEXMAC 
aa 

@ 


Ex 
CMS/DOC 


SDML 


THE SOFTWARE DOCUMENTATION MARKUP LANGUAGE 
© HIGH-LEVEL, STRUCTURALLY ORIENTED “TAGS” 
e GLOBAL TAGS FOR GENERAL USE 


<TABLE> <CHAPTER> 

<CODEXAMPLE> <HEAD1> 

<FIGURE> <HEAD2> 

<NLIST> <SUBHEAD1> 

<ULIST> <SUBHEAD2> 

<TWOCOLLIST> <P> | 


@ TEMPLATES FOR RIGIDLY STRUCTURED ELEMENTS 


<VMS_ROUTINE> (name\full-name) 
<ROUTINE_TYPE>(keyword) <comment>(SYS, RMS, RTL, etc.) 
<OVERVIEW> 
<comment>(Overview paragraph) 
<ENDOVERVIEW> 
<FORMAT> 
<FORMAT>(routine\args,...) | 
<PRTN>(routine) <FARGS>(argl, arg2, arg3,...) 


<JSB_ENTRIES> <comment>(Optional section) 
<JSB> (name ) 


<ENDFORMAT> , 


<RETURNS> (vms-usage\type\access\mechanism[\additional-info]) 


<RETTEXT> . <comment>(Text optional) 
<ENDRETTEXT> <comment>(Required only if <rettext> is specified) 
<ARGDEFLIST> <comment>(Argument definition list) 


<ARGITEM> (name\vms-usage\type\access\mechanism[\additional-info]) 
<ARGDEF>Description of argument... 


<ARGITEM>( ... ) <comment>(repeat for each argument) 
<ARGDEF> 
<ENDARGDEFLIST> 
<DESCRIPTION> <comment>(Description of routine) 
<ENDDESCRIPTION> 
<RSDEFLIST> <comment>(Return status definition list) 


<RSITEM>(status\meaning) 
<RSITEM>(\) <comment>(Repeat for each possible status) 


<ENDRSDEFLIST> 


<EXAMPLES>[ (EXAMPLE) ] <comment>(Numbered examples) 
<EXC> or <EXI> 
<EXTEXT> 


<ENDEXAMPLES> 


Run-Time Library Routines 
LIBSBBCCI 


LIBSBBCCI—tTest and Clear Bit with 
interlock | 
LIBSBBCCI tests and clears a selected bit under memory interlock. 


LIBSBBCCI makes the VAX BBCCI instruction available as a callable 
procedure. 


FORMAT LIBSBBCCI position ,base 


RETURNS VMS Usage: longword_unsigned 
type: aligned bit string 


access: write only 
mechanism: by value 


State of the bit before it was cleared by LIBSBBCCI; 1 if the bit was previously 
set and 0 if the bit was previously clear. 


ARGUMENTS position 


VMS Usage: longword_signed 
type: longword integer (signed) | 
access: read only 


mechanism: by reference 

Bit position, relative to base, of the bit which LIBS$BBCCI tests and clears. 
The position argument is the address of a signed longword integer containing 
the bit position. A pealliod of aero Gascon tic oererder ‘lt of tha bone bane 
The bit position is equal to the offset of the bit chosen from the base position. 
This offset may span the entire range of a signed longword integer; negative 
offsets access bits in lower-addressed bytes. 


base 

VMS Usage: address | 
type: unspecified 
access: read only 


mechanism: by reference 

Byte containing bit zero of the field that LIBSBBCCI references. The base 
argument is the address of the base position. The bit that LIBSBBCCI tests 
and clears is position bits offset from the low bit of base. 


DESCRIPTION = ane bit pl encore by position and base is tested, the previous state of 
embered, and the bit cleared. The reading of the state of the bit 
sat v3 ‘easing are interlocked against similar operations by other processors 
or devices in the system. The remembered previous state of the bit is then 
returned as the function value of LIBSBBCCI. 


For more information, see the VAX-11 Architecture Reference Manual. 


RTL-1 


SDML 


TEMPLATES 


@ ENSURE FORMAT CONSISTENCY AMONG 
DOCUMENTS IN THE SAME FAMILY 


@ ENSURE THAT ALL REQUIRED/RELEVANT 
INFORMATION IS PRESENT 


@ SPECIFIC PIECES OF INFORMATION ARE IN 
KNOWN PLACES AND CAN BE EASILY EXTRACTED 
(E.G. HELP FILES, COMMAND SUMMARIES, QUICK 
REFERENCE GUIDES) 


TEXMAC 


@ READS SDML-CODED FILE 


@ LOOKS TAGS UP IN A “DEFINITION FILE”; 
REPLACES EACH TAG WITH FORMATTING 
COMMANDS. FOR EXAMPLE: 


<DEFINE>(P: 
\paragraph) 


e@ USING DIFFERENT DEFINITION FILES ENABLES 
US TO PRODUCE OUTPUT FOR DIFFERENT TEXT 
PROCESSING PROGRAMS. FOR EXAMPLE, A 
DSRPLUS DEFINITION FILE MIGHT CONTAIN: 


’ <DEFINE>(P: 
.b;) 


EX 


FORMATS INPUT TEXT INTO LINES, PARAGRAPHS, 
AND PAGES 


MACRO PACKAGE DEVELOPED FOR SOFTWARE 
DOCUMENTATION NEEDS 


FORMAT VARIES DEPENDING ON BOOK DESIGN 
(DOCTYPE), OUTPUT DEVICE 


PRODUCES OUTPUT FOR THESE DEVICES: 
AUTOLOGIC MICROS5 TYPESETTER 
LNO1 LASER PRINTER 
LINE PRINTER 
VT100,VT200 TERMINALS 

-LNO3 LASER PRINTER 


CMS/DOC 


“LIBRARIAN® SYSTEM 


SUBSET OF DEC/CMS 
WRITER PUTS SOURCE FILES INTO LIBRARY 
RESTRICTS ACCESS TO SOURCE FILES 


PREVENTS PARALLEL DEVELOPMENT OF SOURCE 
FILES 


TRACKS HISTORY OF DEVELOPMENT OF SOURCE 
FILES 


DOCUMENT: 
THE SOLUTION TO OUR PROBLEMS 


FEATURES OF THE SYSTEM  - 
@ HIGH-QUALITY OUTPUT 


@ FORMATTED DRAFT COPY AVAILABLE EARLY IN 
PRODUCTION CYCLE 


@ DISTRIBUTED MAINTENANCE OF FILES 


@ WRITERS SHIELDED FROM DETAILS OF 
FORMATTING 


@ FORMAT CONSISTENCY WITHIN AND ACROSS 
BOOKS 


@ ABILITY TO ADD NEW, SOPHISTICATED FORMATS 


DOCUMENT 


FEATURES OF THE SYSTEM 


SOFTWARE FOR TRACKING SOURCE FILES 
ENGLISH-LIKE, STRUCTURALLY ORIENTED TAGS 
SOURCE FILES ARE DEVICE INDEPENDENT 
SOURCE FILES ARE FORMAT INDEPENDENT 


ABILITY TO PROCESS COMPLEX TABLES AND 
EXAMPLES 


<doct ype>(manual ) 
<define>(exam_chap\1) 
<define>(list_chap\2) 
<define>(typog chap\3) 
<define>(fig chap\4) 
<define>(note_chap\5) 
<define>(numx_ _chap\6) 
<define>(specials_ chap\7) 
<def ine>(pqdeflist_chap\8) 
<define>(table_chap\9) 
<define>(msg_apx\A 


<define>(ADMIN GUIDE\Administrator's Guide) 
<define>(SDML_PRIM\Getting Started with SDML) 
<define>(SDML_| , UG\SDML User's Guide) 


<chapter>(<note_chap>\Notes and Footnotes) 
KCOMMENL >*AXRAAAHKKKEKKARKRKKKKKEKREKKEREEKEKKKKEEKEKEKEREKRERREKEKEKE 


Testing forms of the NOTE tag. . 


RAEKEKKEKEEKRKEKREKEEEKKEREKKEKKEKKERKREKREKKEKEKEKEREKKKKEKKEKEKK<CONGCcOmMMeNt > 


<P>This chapter illustrates the <tag>(NOTE), <tag>(NOTES), 

and <tag>(FOOTNOTE) tags. 

<include>(text.dat) 

<Headl>(Vanilla Notes) 

<P>The first note includes a list. 

<note>The CROSS directive has these attributes: } 
<NLIST><LE>CROSS without a symbol list will not reenable the cross-reference 
listing of a symbol specified in .NOCROSS with a symbol list. 


<LE>If the cross-reference listing of all symbols is disabled, .CROSS 
with a symbol list will have no effect until the cross-reference listing 
is reenabled by .CROSS without a symbol list. 

<ELS> 

<ENDNOTE> 

<include>(text.dat) 

<P>A long note, with a table in it: 


<note> 

-This is a branch instruction. The groups: 
<nlist> 

<le>Overflow and carry group 
<twocollist>(5) 

<twocols>(BVS\V EQL 1) 

<twocols>(BVC\V EQL 0) 

<twocols>(VCS\C EQL 1) 

<ENDtwocollist> 


<le>Unsigned group: 
<twocollist>(7) 
<twocols>(BLSSU\C EQL 1) 
<twocols>(BLEQU\{C OR Z} EQL 1) 
<endtwocollist> 

<ELS> 


<P>Here is an additional paragraph inside this note with more text. 
<endnote> 


i Notes and Footnotes 


This chapter illustrates the <NOTE>, < NOTES>, and 
<FOOTNOTE> tags. 


Flashy designs are inappropriate for software manuals or for 
any serious or formal books because they do not reflect the 
intention of the writer. The purpose of any book design is 
to clarify what the author is conveying, to translate the text 
attractively as print on a page, to communicate the message 
visually in harmony with the ideas. 


5.1 Vanilla Notes 


The first note includes a list. 
Note: The CROSS directive has these attributes: 


1 CROSS without a symbol list will not reenable the cross- 
reference listing of a symbol specified in NOCROSS 
with a symbol list. 


2 If the cross-reference listing of all symbols is disabled, 
-CROSS with a symbol list will have no effect until the 
cross-reference listing is reenabled by .CROSS without a 


symbol! list. 


Flashy designs are inappropriate for software manuals or for 
any serious or formal books because they do not reflect the 
intention of the writer. The purpose of any book design is 
to clarify what the author is conveying, to translate the text 
attractively as print on a page, to communicate the ee 
visually in harmony with the ideas. 


A long note, with a table in it 
Note: This is a branch instruction. The groups: 


Chapter 5 
Notes and Footnotes 


This chapter illustrates the < NOTE> , < NOTES>, and < FOOTNOTE> tags. 


Flashy designs are inappropriate for software manuals or for any serious 
or formal books because they do not reflect the intention of the writer. 
The purpose of any book design is to clarify what the author is conveying, 
to translate the text attractively as print on a page, to communicate the 
message visually in harmony with the ideas. 


5.1 Vanilla Notes 
The first note includes a list. 
Note 
The CROSS directive has these attributes: 


1. CROSS without a symbol list will not reenable 
the cross-reference listing of a symbol specified in 
-NOCROSS with a symbol list. 


2. If the cross-reference listing of all symbols is disabled, 
-CROSS with a symbol list will have no effect until the 
cross-reference listing is reenabled by .CROSS without 
a symbol list. 
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Chapter 5 
Notes and Footnotes 


This chapter illustrates the < NOTE>, <NOTES> , and < FOOTNOTE> tags. 


Flashy designs are inappropriate for software manuals or for any serious 
or formal books because they do not reflect the intention of the writer. 
The purpose of any book design is to clarify what the author is conveying, 
to translate the text attractively as print on a page, to communicate the 
message visually in harmony with the ideas. 


5.1 Vanilla Notes 


The first note includes a list. 


NOTE 
The CROSS directive has these attributes: | 


1. CROSS without a symbol list will not reenable the cross- 
reference listing of a symbol specified in .NOCROSS with a 
symbol list. 

2. If the cross-reference listing of all symbols is disabled, 
-CROSS with a symbol list will have no effect until the 
cross-reference listing is reenabled by .CROSS without a 
symbol! list. Pre 


Flashy designs are inappropriate for software manuals or for any serious 
or formal books because they do not reflect the intention of the writer. 
The purpose of any book design is to clarify what the author is conveying, 
to translate the text attractively as print on a page, to communicate the 
message visually in harmony with the ideas. 
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DOCUMENT 


AUTOMATED FEATURES OF THE SYSTEM 


PAGINATION 

SOPHISTICATED HYPHENATION 
KERNING, LIGATURES, MATH SYMBOLS 
INDEX AND TOC GENERATION 
RUNNING HEADS AND FOLIOS 
HEADING AND SECTION NUMBERING 
OUTLINE GENERATION 


DOCUMENT 


PRESENT DEVELOPMENT PLANS 
INTEGRATION OF TEXT AND GRAPHICS 
LSE INTERFACE 

PREVIEW TERMINAL 

ON-LINE DOCUMENTATION 


